home *** CD-ROM | disk | FTP | other *** search
/ Apple WWDC 1996 / WWDC96_1996 (CD).toast / Technology Materials / MacOS 8 Resources / Developer Tools / Mac OS 8 Interfaces & Libraries / Interfaces / CIncludes / DeviceNotify.h < prev    next >
C/C++ Source or Header  |  1996-05-01  |  9KB  |  262 lines
  1. /*
  2.      File:        DeviceNotify.h
  3.  
  4.      Contains:    xxx put contents here xxx
  5.  
  6.      Version:    Technology:    xxx put the technology version here xxx
  7.                  Release:    Universal Interfaces 3.0d3 on Copland DR1
  8.  
  9.      Copyright:    © 1984-1996 by Apple Computer, Inc.  All rights reserved.
  10.  
  11.      Bugs?:        If you find a problem with this file, send the file and version
  12.                  information (from above) and the problem description to:
  13.  
  14.                      Internet:    apple.bugs@applelink.apple.com
  15.                      AppleLink:    APPLE.BUGS
  16.  
  17. */
  18. #ifndef __DEVICENOTIFY__
  19. #define __DEVICENOTIFY__
  20.  
  21. #ifndef __TYPES__
  22. #include <Types.h>
  23. #endif
  24. #ifndef __KERNEL__
  25. #include <Kernel.h>
  26. #endif
  27. #ifndef __NAMEREGISTRY__
  28. #include <NameRegistry.h>
  29. #endif
  30.  
  31. #ifdef __cplusplus
  32. extern "C" {
  33. #endif
  34.  
  35. #if PRAGMA_IMPORT_SUPPORTED
  36. #pragma import on
  37. #endif
  38.  
  39. #if PRAGMA_ALIGN_SUPPORTED
  40. #pragma options align=mac68k
  41. #endif
  42.  
  43. #if FOR_SYSTEM8_PREEMPTIVE
  44. /*
  45.  ß
  46. ##############################################################################
  47.     
  48.     File Name: DeviceNotifyPriv.h
  49.     
  50.     Description:
  51.                             The device notification service is used by Copland Kernel band
  52.                     Low level family expert code to inform high level "consumers" about
  53.                 hot plugging/un-plugging of devices.
  54.                 
  55.                 The High level families or code modules running in priviledged mode 
  56.                 can subscribe to the service with the DevNRegisterInterestIn().
  57.                 LL Family notifies its consumers through the DevNNotifyThatThisChanged().
  58.     
  59. ##############################################################################
  60. ############################
  61.  Defines
  62. ############################
  63. */
  64. typedef UInt32 DevNRef;
  65. /*
  66.      a connection Reference Num for a particular subscription
  67.                                         a consumer subscription is identified by a unique
  68.                                          DevNSubRef. In order to cancel a consumer registration,
  69.                                         the DevNSubRef must be specified.
  70.                                     
  71.                                         a  Reference Num for a particular notification
  72.                                         A notification is identified by a unique DevNRef,
  73.                                         since a notification can go through couple of states, and 
  74.                                         it needs to be tracked with a unique identifier.
  75.                                     
  76. */
  77. /*
  78.  ß
  79. ########################################################################
  80.     Known & valid Service Category definitions are defined in DFM.h
  81. ########################################################################
  82. */
  83.  
  84. enum {
  85.     kDevNAllServiceCategories    = 0xFFFFFFFF                    /* an option to subscribe to ALL valid service catagories*/
  86. };
  87.  
  88.  
  89. enum {
  90.     kMaxNumServiceCategories    = 20                            /* ***†should be in DFM.h ****/
  91. };
  92.  
  93. /*
  94.  ß
  95. ########################################################################
  96.  Event definition:
  97.     If kDevNSoftRequestMask is set in conjunction with an event value,
  98.     then a soft request is indicated, and the DevN will handle all the
  99.     drudgery associated with two-way transactions, etc.
  100.     (e.g. If (kDevNRemoved and kDevNSoftRequestMask) is received, it's 
  101.     a soft eject request)
  102.     If kDevNSoftRequestMask is NOT set, then it's a hard request
  103.      If the kDevNWarningMask is set, then it's an event warning that 
  104.     a given event is about to happen (and the consumer can't do a thing
  105.     about it). It will be followed later on by a gone hard event.
  106.     the kDevNWarningMask and the kDevNSoftRequestMask can NOT be set at
  107.     the same time.
  108. ########################################################################
  109. */
  110. typedef UInt32 DevNEventType;
  111. /*
  112.  pre-defined event mask
  113.  ß
  114.  definition of valid global event
  115.  (10/11/95) Events are now enum instead of masks
  116.  enum for "unsigned" values
  117. */
  118.  
  119. enum {
  120.     kDevNSoftRequestMask        = 0x80000000,                    /* bit indicating soft request*/
  121.     kDevNWarningMask            = 0x40000000,                    /* bit indicating a warning request*/
  122.     kDevNAdded                    = 0,                            /* New device/media/bus available*/
  123.     kDevNRemoved                = 1,                            /* Existing device/media/bus now gone*/
  124.     kDevNWakeup                    = 2,                            /* Plug-in sw state no longer needs synchronization*/
  125.     kDevNSleep                    = 3,                            /* Ask to synchronize SOFTWARE state of plug-in*/
  126.                                                                 /* ...used by PowerMgr, DriverReplacer, Soft Dev Eject*/
  127.     kDevNBootComplete            = 4,                            /* used by motherboard expert to inform DFM boot complete*/
  128.     kDevNIOInitComplete            = 5,                            /* I/O system initialize complete*/
  129.     kDevNNumOfPredefinedEvtInUse = 6,
  130.     kDevNHighestEvtInUse        = 5
  131. };
  132.  
  133. /* enum for "signed" values*/
  134.  
  135. enum {
  136.     kDevNSoftEject                = 0x80000001                    /* (kDevNRemoved | kDevNSoftRequestMask)*/
  137. };
  138.  
  139. /*
  140.  ß
  141. ########################################################################
  142.     Routine return value definition
  143. ########################################################################
  144. */
  145. typedef UInt32 DevNPermissionResponse;
  146. /* status returned by consumer to DevN*/
  147.  
  148. enum {
  149.     kDevNPermissionGranted        = 0,                            /* consumer consented that instant removal of*/
  150.                                                                 /* node is OK */
  151.     kDevNPermissionDelayed        = 1,                            /* can not grant permission now, will inform producer through .*/
  152.                                                                 /* DevN at a later time (ignored by the DevN if hard request) */
  153.     kDevNPermissionDenied        = 2,                            /* do Not allow requested event to take place*/
  154.                                                                 /*    (ignored by the DevN if hard request)*/
  155.     kDevNValidPermissionMasks    = 3
  156. };
  157.  
  158. /*
  159. ########################################################################
  160.     Error code definition
  161. ########################################################################
  162. */
  163.  
  164. enum {
  165.     kDevNMErrorCodeBase            = 0,
  166.     kInvalidSC                    = kDevNMErrorCodeBase + 1,        /* subscribe with invalid Service Category code*/
  167.     kInvalidEvent                = kDevNMErrorCodeBase + 2,        /* subscribe with invalid event mask (zero)*/
  168.     kInvalidHandler                = kDevNMErrorCodeBase + 3,        /* subscribe with NULL handler address*/
  169.     kNoSuchRef                    = kDevNMErrorCodeBase + 4,        /* Specified ID can not be found*/
  170.     kRecordNotFound                = kDevNMErrorCodeBase + 5,        /* while unregistering, can not find record in array*/
  171.     kNotEnoughEventMask            = kDevNMErrorCodeBase + 6,        /* not enough masks for DevNMCreateNewEvent call*/
  172.     kDeleteInvalidMasks            = kDevNMErrorCodeBase + 7,        /* attempt to DevNMDeleteNewEvent on invalid event masks*/
  173.     kInvalidEventCount            = kDevNMErrorCodeBase + 8,        /* invalid event count parameter being passed in*/
  174.     kInvalidPermission            = kDevNMErrorCodeBase + 9,        /* bad permission returned from consumer*/
  175.     kTokenNotFound                = kDevNMErrorCodeBase + 10        /* sub record lookup list token not found*/
  176. };
  177.  
  178. /*
  179. ########################################################################
  180.     Subroutine Prototype
  181. ########################################################################
  182.  no more handlers
  183. ######################                    
  184.  called by consumer
  185. ######################    
  186. */
  187. extern OSStatus DevNRegisterInterestIn(OSType myFamily, ItemCount eventCount, DevNEventType *events, ObjectID adminMessageObj, DevNRef *thisRegistration, void *parm);
  188.  
  189. extern OSStatus DevNUnregisterInterest(DevNRef thisID);
  190.  
  191. extern OSStatus DevNMCreateNewEvent(DevNEventType *result);
  192.  
  193. /*
  194.  call to register family defined events.
  195.  itemCount specifies how many events are desired
  196.     (Only create one event at a time)
  197. */
  198. extern OSStatus DevNMDeleteNewEvent(DevNEventType event);
  199.  
  200. /* de-register the given event*/
  201. extern OSStatus DevNDelayedDownwardNotify(DevNRef notifyRef, DevNRef subscriptionRef, DevNPermissionResponse permission);
  202.  
  203. /*
  204.  must be called after an kDevNPermissionDelayed is returned to the DevN
  205.     for a notification response.
  206. ######################                    
  207.  called by producer
  208. ######################                    
  209. */
  210. extern DevNPermissionResponse DevNNotifyThatThisChanged(OSType whichServiceCategory, DevNEventType whatHappened, RegEntryRef *whichDevice, ObjectID adminMessageObj, DevNRef *notRef, void *parm);
  211.  
  212. extern DevNPermissionResponse DevNNotifyEvents(DevNEventType whatHappened, RegEntryRef *whichDevice, ObjectID adminMessageObj, DevNRef *notRef, void *parm);
  213.  
  214. /*
  215. #####################################
  216.  Notification Message definitions        
  217. #####################################
  218. */
  219. struct DevNMessage {
  220.     UInt32                             AdminMessageType;
  221.     UInt32                             subMessageType;
  222.     OSType                             serviceCategory;
  223.     DevNEventType                     event;
  224.     RegEntryRef *                    device;
  225.     void *                            parm;
  226.     DevNRef                         notRef;
  227.     DevNPermissionResponse             returnPermission;
  228. };
  229. typedef struct DevNMessage DevNMessage;
  230.  
  231. /*
  232. #########################################################
  233.     Device Notification sub-message types.    
  234.     (This is in the "subMessageType" field inside
  235.         The DevNMessage structure)
  236. #########################################################
  237. */
  238.  
  239. enum {
  240.     kDevNNotifyMsg                = 0x01,
  241.     kDevNNotifyCancel            = 0x02,
  242.     kDevNNotifyDelayedReply        = 0x03,
  243.     kNextUnusedMsg                = 0x04
  244. };
  245.  
  246. #endif
  247.  
  248. #if PRAGMA_ALIGN_SUPPORTED
  249. #pragma options align=reset
  250. #endif
  251.  
  252. #if PRAGMA_IMPORT_SUPPORTED
  253. #pragma import off
  254. #endif
  255.  
  256. #ifdef __cplusplus
  257. }
  258. #endif
  259.  
  260. #endif /* __DEVICENOTIFY__ */
  261.  
  262.